<HTML>
<CENTER><A HREF = "http://pizza.sandia.gov">Pizza.py WWW Site</A> - <A HREF = "Manual.html">Pizza.py Documentation</A> - <A HREF = "Section_tools.html">Pizza.py Tools</A> 
</CENTER>






<HR>

<H3>matlab tool 
</H3>
<P><B>Purpose:</B>
</P>
<P>Create plots via MatLab numerical analysis program.
</P>
<P><B>Description:</B>
</P>
<P>The matlab tool is a wrapper on the <A HREF = "http://www.mathworks.com">MatLab</A>
numerical analysis package, primarily designed to use its plotting
capabilities.  MatLab is commercial software available on a variety
of platforms.
</P>
<P>The matlab constructor launches MatLab as a process which the matlab
tool sends commands to.  The MatLab process can be killed via the
stop() method, though this is typically unnecessary.
</P>
<P>The plot() method plots a single vector against a linear index or
pairs of vectors against each other.  The pairs of vectors are written
to files and read-in by MatLab.  The Nth curve in a plot is stored in
the MatLab variable pizzaN, so the 2 vectors can be accessed within
MatLab as pizzaN(:,1) and pizzaN(:,2).
</P>
<P>The mplot() method creates a series of plots and saves them each to a
numbered file.  Each file is a plot of an increasing portion of the
vector(s).  This can be used to make an animation of a plot.
</P>
<P>The enter() method can be used to interact with MatLab directly.
Each subsequent line you type is a MatLab command, until you type
"quit" or "exit" to return to Pizza.py.  Single MatLab commands can
be issued as string arguments to the gnu tool.
</P>
<P>The export() method writes numeric data as columns to text files, so
that MatLab can read them via its "importdata" command.
</P>
<P>Mutliple windows can be displayed, plotted to, and manipulated using
the select() and hide() methods.  The save() method writes the
currently selected plot to a PostScript file.
</P>
<P>The remaining methods (aspect, title, xrange, etc) set attributes of
the currently selected plot.  The erase() method resets all attributes
to their default values.
</P>
<P><B>Usage:</B>
</P>
<PRE>m = matlab()		       start up MatLab
m.stop()		       shut down MatLab process 
</PRE>
<PRE>m.plot(a)                      plot vector A against linear index
m.plot(a,b)	 	       plot B against A
m.plot(a,b,c,d,...)	       plot B against A, D against C, etc
m.mplot(M,N,S,"file",a,b,...)  multiple plots saved to file0000.eps, etc 
</PRE>
<PRE>  each plot argument can be a tuple, list, or Numeric/NumPy vector
  mplot loops over range(M,N,S) and create one plot per iteration
    last args are same as list of vectors for plot(), e.g. 1, 2, 4 vectors
    each plot is made from a portion of the vectors, depending on loop index i
      Ith plot is of b[0:i] vs a[0:i], etc
    series of plots saved as file0000.eps, file0001.eps, etc
    if use xrange(),yrange() then plot axes will be same for all plots 
</PRE>
<PRE>m("c = a + b")                 execute string in MatLab 
</PRE>
<PRE>m.enter()	   	       enter MatLab shell
matlab> c = a + b              type commands directly to MatLab
matlab> exit, quit	       exit MatLab shell 
</PRE>
<PRE>m.export("data",range(100),a,...)       create file with columns of numbers 
</PRE>
<PRE>  all vectors must be of equal length
  could plot from file with MatLab commands:
    cols = importdata('data')
    plot(cols(:,1),cols(:,2)) 
</PRE>
<PRE>m.select(N)  	               figure N becomes the current plot 
</PRE>
<PRE>  subsequent commands apply to this plot 
</PRE>
<PRE>m.hide(N)  	               delete window for figure N
m.save("file")	               save current plot as file.eps 
</PRE>
<PRE>Set attributes for current plot: 
</PRE>
<PRE>m.erase()                      reset all attributes to default values
m.aspect(1.3)                  aspect ratio
m.xtitle("Time")               x axis text
m.ytitle("Energy")             y axis text
m.title("My Plot")             title text
m.title("title","x","y")       title, x axis, y axis text
m.xrange(xmin,xmax)            x axis range
m.xrange()                     default x axis range
m.yrange(ymin,ymax)            y axis range
m.yrange()                     default y axis range
m.xlog()                       toggle x axis between linear and log
m.ylog()                       toggle y axis between linear and log
m.label(x,y,"text")            place label at x,y coords
m.curve(N,'r')                 set color of curve N
m.curve(N,'g','--')            set color and line style of curve N
m.curve(N,'b','-','v')         set color, line style, symbol of curve N 
</PRE>
<PRE>  colors:  'k' = black, 'r' = red, 'g' = green, 'b' = blue
           'm' = magenta, 'c' = cyan, 'y' = yellow
  styles:  '-' = solid, '--' = dashed, ':' = dotted, '-.' = dash-dot
  symbols: '+' = plus, 'o' = circle, '*' = asterik, 'x' = X,
           's' = square, 'd' = diamond, '^' = up triangle,
           'v' = down triangle, '>' = right triangle,
           '<' = left triangle, 'p' = pentagram, 'h' = hexagram 
</PRE>
<P><B>Related tools:</B>
</P>
<P><A HREF = "gnu.html">gnu</A>, <A HREF = "plotview.html">plotview</A>
</P>
<P><B>Prerequisites:</B>
</P>
<P>The MatLab numerical analysis package.
</P>
</HTML>
